home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / library / reqtlsdv.lha / ReqTools / Glue / M2Sprint / m2sprint_glue.lha / ReqTools.def < prev    next >
Text File  |  1992-02-13  |  55KB  |  1,305 lines

  1. DEFINITION MODULE ReqTools;
  2.  
  3. (*
  4. **    $Filename: libraries/reqtools.h $
  5. **    $Release: 1.0 $
  6. **
  7. **    (C) Copyright 1991 Nico François
  8. **        All Rights Reserved
  9. *)
  10.  
  11. FROM SYSTEM        IMPORT ADDRESS, BYTE, STRPTR;
  12. FROM DOS           IMPORT BPTR;
  13. FROM DOSExtensions IMPORT DOSBaseRecPtr;
  14. FROM GfxBase       IMPORT GfxBaseRecPtr;
  15. FROM Hooks         IMPORT HookPtr;
  16. FROM Intuition     IMPORT ScreenPtr, NewWindowPtr, WindowPtr;
  17. FROM IntuitionBase IMPORT IntuitionBaseRecPtr;
  18. FROM Libraries     IMPORT Library, LibraryPtr;
  19. FROM Tasks         IMPORT SignalSet;
  20. FROM Text          IMPORT TextAttr, TextFontPtr;
  21. FROM TagItem       IMPORT TagItemPtr, TAGUSER;
  22.  
  23.  
  24. CONST
  25.   ReqToolsName    = "reqtools.library";
  26.   ReqToolsVersion = 37;
  27.  
  28. TYPE
  29.   ReqToolsBaseRecPtr = POINTER TO ReqToolsBaseRec;
  30.   ReqToolsBaseRec =
  31.    RECORD
  32.      LibNode       : Library;
  33.      Flags         : BYTE;
  34.      pad           : ARRAY [0..3] OF BYTE;
  35.      SegList       : BPTR;
  36.  
  37.      (* The following library bases may be read and used by your program *)
  38.      IntuitionBase : IntuitionBaseRecPtr;
  39.      GfxBase       : GfxBaseRecPtr;
  40.      DOSBase       : DOSBaseRecPtr;
  41.  
  42.      (* Next two library bases are only (and always) valid on Kickstart 2.0!
  43.       (1.3 version of reqtools also initializes these when run on 2.0) *)
  44.      GadToolsBase  : LibraryPtr;
  45.      UtilityBase   : LibraryPtr;
  46.    END;
  47.  
  48. VAR
  49.   ReqToolsBase : ReqToolsBaseRecPtr;  (* initialized by OpenReqToolsLib *)
  50.  
  51.  
  52. (* types of requesters, for rtAllocRequestA() *)
  53. CONST
  54.   RTFILEREQ    = 0;
  55.   RTREQINFO    = 1;
  56.   RTFONTREQ    = 2;
  57.  
  58. (***************************************
  59. * flags for RTFI_Flags and RTFO_Flags  *
  60. * or filereq->Flags and fontreq->Flags *
  61. ***************************************)
  62. TYPE
  63.   FReqFlags = (MultiSelect, Save, NoBuffer, NoFiles, PadGad, FixedWidth,
  64.                ColorFonts, ChangePalette, LeavePalette, Scale, Style,
  65.                DoWildFunc, SelectDirs, FRTBD13, FRTBD14, FRTBD15, FRTBD16,
  66.                FRTBD17, FRTBD18, FRTBD19, FRTBD20, FRTBD21, FRTBD22, FRTBD23,
  67.                FRTBD24, FRTBD25, FRTBD26, FRTBD27, FRTBD28, FRTBD29, FRTBD30,
  68.                FRTBD31);
  69.   FReqFlagSet = SET OF FReqFlags;
  70.  
  71. (***********************
  72. *                      *
  73. *    File requester    *
  74. *                      *
  75. ***********************)
  76.  
  77. (* structure _MUST_ be allocated with rtAllocRequest() *)
  78. TYPE
  79.   rtFileRequesterPtr = POINTER TO rtFileRequester;
  80.   rtFileRequester =
  81.     RECORD
  82.       ReqPos      : LONGINT;
  83.       LeftOffset  : INTEGER;
  84.       TopOffset   : INTEGER;
  85.       Flags       : FReqFlagSet;
  86.       Hook        : HookPtr;
  87.       Dir         : STRPTR;   (* READ ONLY! Change with rtChangeReqAttrA()! *)
  88.       MatchPat    : STRPTR;   (* READ ONLY! Change with rtChangeReqAttrA()! *)
  89.       DefaultFont : TextFontPtr;
  90.       WaitPointer : LONGINT
  91.       (* Lots of private data follows! HANDS OFF :-) *)
  92.     END;
  93.  
  94. (* returned by rtFileRequestA() if multiselect is enabled,
  95.    free list with rtFreeFileList() *)
  96.   rtFileListPtr = POINTER TO rtFileList;
  97.   rtFileList =
  98.     RECORD
  99.       Next   : rtFileListPtr;
  100.       StrLen : LONGINT;             (* -1 for directories *)
  101.       Name   : STRPTR;
  102.     END;
  103.  
  104. (***********************
  105. *                      *
  106. *    Font requester    *
  107. *                      *
  108. ***********************)
  109.  
  110. (* structure _MUST_ be allocated with rtAllocRequest() *)
  111.  
  112.   rtFontRequesterPtr = POINTER TO rtFontRequester;
  113.   rtFontRequester =
  114.     RECORD
  115.       ReqPos      : LONGINT;
  116.       LeftOffset  : INTEGER;
  117.       TopOffset   : INTEGER;
  118.       Flags       : FReqFlagSet;
  119.       Hook        : HookPtr;
  120.       Attr        : TextAttr;        (* READ ONLY! *)
  121.       DefaultFont : TextFontPtr;
  122.       WaitPointer : LONGINT
  123.       (* Lots of private data follows! HANDS OFF :-) *)
  124.     END;
  125.  
  126. (*****************************************
  127. * flags for RTEZ_Flags or reqinfo->Flags *
  128. *****************************************)
  129. TYPE
  130.   EZReqFlags = (NoReturnKey, LAmigaQual, CenterText,
  131.                 EZTBD3, EZTBD4, EZTBD5, EZTBD6, EZTBD7, EZTBD8, EZTBD9,
  132.                 EZTBD10, EZTBD11, EZTBD12, EZTBD13, EZTBD14, EZTBD15, EZTBD16,
  133.                 EZTBD17, EZTBD18, EZTBD19, EZTBD20, EZTBD21, EZTBD22, EZTBD23,
  134.                 EZTBD24, EZTBD25, EZTBD26, EZTBD27, EZTBD28, EZTBD29, EZTBD30,
  135.                 EZTBD31);
  136.   EZReqFlagSet = SET OF EZReqFlags;
  137.  
  138. (***********************
  139. *                      *
  140. *    Requester Info    *
  141. *                      *
  142. ***********************)
  143.  
  144. (* for rtEZRequest(), rtGetLong(), rtGetString() and rtPaletteRequest(),
  145.    _MUST_ be allocated with rtAllocRequest() *)
  146.  
  147.   rtReqInfoPtr = POINTER TO rtReqInfo;
  148.   rtReqInfo =
  149.     RECORD
  150.       ReqPos      : LONGINT;
  151.       LeftOffset  : INTEGER;
  152.       TopOffset   : INTEGER;
  153.       Width       : LONGINT;       (* not for rtEZRequest() *)
  154.       ReqTitle    : STRPTR;        (* currently only for rtEZRequest() *)
  155.       Flags       : EZReqFlagSet;  (* only for rtEZRequest() *)
  156.       DefaultFont : TextFontPtr;   (* currently only for rtPaletteRequest() *)
  157.       WaitPointer : LONGINT
  158.       (* structure may be extended in future *)
  159.     END;
  160.  
  161. (***********************
  162. *                      *
  163. *     Handler Info     *
  164. *                      *
  165. ***********************)
  166.  
  167. (* for rtReqHandlerA(), will be allocated for you when you use
  168.    the RT_ReqHandler tag, never try to allocate this yourself! *)
  169.  
  170.   rtHandlerInfoPtr = POINTER TO rtHandlerInfo;
  171.   rtHandlerInfo =
  172.     RECORD
  173.       private1  : LONGINT;
  174.       WaitMask  : LONGINT;
  175.       DoNotWait : LONGINT
  176.       (* Private data follows, HANDS OFF :-) *)
  177.     END;
  178.  
  179. (* possible return codes from rtReqHandlerA() *)
  180. CONST
  181.   CallHandler = 80000000H;
  182.  
  183.  
  184. (*************************************
  185. *                                    *
  186. *                TAGS                *
  187. *                                    *
  188. *************************************)
  189.  
  190.   RTTagBase   = TAGUSER;
  191.  
  192.   (*** tags understood by most requester functions ***)
  193.   (* optional pointer to window *)
  194.   RTWindow         = RTTagBase+1;
  195.  
  196.   (* idcmp flags requester should abort on (useful for IDCMP_DISKINSERTED) *)
  197.   RTIDCMPFlags         = RTTagBase+2;
  198.  
  199.   (* position of requester window (see below) - default REQPOS_POINTER *)
  200.   RTReqPos         = RTTagBase+3;
  201.  
  202.   (* signal mask to wait for abort signal *)
  203.   RTLeftOffset         = RTTagBase+4;
  204.  
  205.   (* topedge offset of requester relative to position specified by RTReqPos *)
  206.   RTTopOffset         = RTTagBase+5;
  207.  
  208.   (* name of public screen to put requester on (Kickstart 2.0 only!) *)
  209.   RTPubScrName         = RTTagBase+6;
  210.  
  211.   (* address of screen to put requester on *)
  212.   RTScreen         = RTTagBase+7;
  213.  
  214.   (* tagdata must hold the address of (!) an APTR variable *)
  215.   RTReqHandler         = RTTagBase+8;
  216.  
  217.   (* font to use when screen font is rejected, _MUST_ be fixed-width font!
  218.    (struct TextFont *, not struct TextAttr - default GfxBase->DefaultFont *)
  219.   RTDefaultFont         = RTTagBase+9;
  220.  
  221.   (* boolean to set the standard wait pointer in window - default FALSE *)
  222.   RTWaitPointer         = RTTagBase+10;
  223.  
  224.   (*** tags specific to rtEZRequest ***)
  225.   (* title of requester window - default "Request" or "Information" *)
  226.   RTEZReqTitle         = RTTagBase+20;
  227.  
  228.   (* (RTTagBase+21) reserved   *)
  229.   (* various flags (see below) *)
  230.   RTEZFlags         = RTTagBase+22;
  231.  
  232.   (* default response (activated by pressing RETURN) - default TRUE *)
  233.   RTEZDefaultResponse     = RTTagBase+23;
  234.  
  235.   (*** tags specific to rtGetLongA ***)
  236.   (* minimum allowed value - default MININT *)
  237.   RTGLMin         = RTTagBase+30;
  238.  
  239.   (* maximum allowed value - default MAXINT *)
  240.   RTGLMax         = RTTagBase+31;
  241.  
  242.   (* suggested width of requester window (in pixels) *)
  243.   RTGLWidth         = RTTagBase+32;
  244.  
  245.   (* boolean to show the default value - default TRUE *)
  246.   RTGLShowDefault     = RTTagBase+33;
  247.  
  248.   (*** tags specific to rtGetStringA ***)
  249.   (* suggested width of requester window (in pixels) *)
  250.   RTGSWidth         = RTGLWidth;
  251.  
  252.   (* allow empty string to be accepted - default FALSE *)
  253.   RTGSAllowEmpty     = RTTagBase+80;
  254.  
  255.   (*** tags specific to rtFileRequestA ***)
  256.   (* various flags (see below) *)
  257.   RTFIFlags         = RTTagBase+40;
  258.  
  259.   (* suggested height of file requester *)
  260.   RTFIHeight         = RTTagBase+41;
  261.  
  262.   (* replacement text for 'Ok' gadget (max 6 chars) *)
  263.   RTFIOkText         = RTTagBase+42;
  264.  
  265.   (*** tags specific to rtFontRequestA ***)
  266.   (* various flags (see below) *)
  267.   RTFOFlags         = RTFIFlags;
  268.  
  269.   (* suggested height of font requester *)
  270.   RTFOHeight         = RTFIHeight;
  271.  
  272.   (* replacement text for 'Ok' gadget (max 6 chars) *)
  273.   RTFOOkText         = RTFIOkText;
  274.  
  275.   (* suggested height of font sample display - default 24 *)
  276.   RTFOSampleHeight     = RTTagBase+60;
  277.  
  278.   (* minimum height of font displayed *)
  279.   RTFOMinHeight         = RTTagBase+61;
  280.  
  281.   (* maximum height of font displayed *)
  282.   RTFOMaxHeight         = RTTagBase+62;
  283.  
  284.   (* [(RTTagBase+63) to (RTTagBase+66) used below] *)
  285.   (*** tags for rtChangeReqAttrA ***)
  286.   (* file requester - set directory *)
  287.   RTFIDir         = RTTagBase+50;
  288.  
  289.   (* file requester - set wildcard pattern *)
  290.   RTFIMatchPat         = RTTagBase+51;
  291.  
  292.   (* file requester - add a file or directory to the buffer *)
  293.   RTFIAddEntry         = RTTagBase+52;
  294.  
  295.   (* file requester - remove a file or directory from the buffer *)
  296.   RTFIRemoveEntry     = RTTagBase+53;
  297.  
  298.   (* font requester - set font name of selected font *)
  299.   RTFOFontName         = RTTagBase+63;
  300.  
  301.   (* font requester - set font size *)
  302.   RTFOFontHeight     = RTTagBase+64;
  303.  
  304.   (* font requester - set font style *)
  305.   RTFOFontStyle         = RTTagBase+65;
  306.  
  307.   (* font requester - set font flags *)
  308.   RTFOFontFlags         = RTTagBase+66;
  309.  
  310.   (*** tags for rtPaletteRequestA ***)
  311.   (* initially selected color - default 1 *)
  312.   RTPAColor         = RTTagBase+70;
  313.  
  314.   (*** tags for rtReqHandlerA ***)
  315.   (* end requester by software control, set tagdata to REQCANCEL, REQOK or
  316.      in case of rtEZRequest to the return value *)
  317.   RTRHEndRequest     = RTTagBase+60;
  318.  
  319.   (*** tags for rtAllocRequestA ***)
  320.   (* no tags defined yet *)
  321.  
  322.  
  323. (************
  324.  * RTReqPos *
  325.  ************)
  326.   REQPOSPOINTER        = 0;
  327.   REQPOSCENTERWIN    = 1;
  328.   REQPOSCENTERSCR    = 2;
  329.   REQPOSTOPLEFTWIN    = 3;
  330.   REQPOSTOPLEFTSCR    = 4;
  331.  
  332. (******************
  333.  * RTRHEndRequest *
  334.  ******************)
  335.   REQCANCEL        = 0;
  336.   REQOK            = 1;
  337.  
  338. (********
  339.  * hooks *
  340.  ********)
  341.   REQHOOKWILDFILE    = 0;
  342.   REQHOOKWILDFONT    = 1;
  343.  
  344.  
  345. (*
  346.  *   reqtools.library   © 1991 Nico François
  347.  *
  348.  *   Modula-2 Interface © 1992 Michael Griebling
  349.  *
  350.  *)
  351.  
  352.  
  353. PROCEDURE OpenReqToolsLib() : BOOLEAN;
  354. (* Open the Requester Tools Library and return TRUE if successful. *)
  355.  
  356.  
  357. PROCEDURE AllocRequestA(type : LONGINT; taglist : TagItemPtr) : ADDRESS;
  358. INLINE(ReqToolsBase, -30, 0, 8);
  359. (*
  360.     Allocates a requester structure for you in a future compatible manner.
  361.     This is the only way to properly allocate a rtFileRequester,
  362.     rtFontRequester or rtReqInfo structure.  The structure will be
  363.     initialized for you.
  364.  
  365.     Use rtFreeRequest() to free the requester structure when you no longer
  366.     need it.
  367.  
  368.   INPUTS
  369.     type    - type of structure to allocate, currently RT_REQINFO,
  370.               RT_FILEREQ or RT_FONTREQ.
  371.     taglist - pointer to array of tags (currently always NULL).
  372.  
  373.   RESULT
  374.     req - pointer to the requester allocated or NULL if no memory.
  375. *)
  376.  
  377. PROCEDURE AllocRequest(type : LONGINT) : ADDRESS;
  378.  
  379.  
  380. PROCEDURE FreeRequest(req : ADDRESS);
  381. INLINE(ReqToolsBase, -36, 9);
  382. (*
  383.     Free requester structure previously allocated by rtAllocRequest().
  384.     This will also free all buffers associated with the requester, so there
  385.     is no need to call rtFreeReqBuffer() first.
  386.  
  387.     req - pointer to requester (may be NULL).
  388. *)
  389.  
  390.  
  391. PROCEDURE FreeReqBuffer(req : ADDRESS);
  392. INLINE(ReqToolsBase, -42, 9);
  393. (*
  394.     Frees the buffer associated with 'req'.  In case of a file requester this
  395.     function will deallocate the directory buffer, in case of a font
  396.     requester the font list.
  397.  
  398.     It is safe to call this function for requesters that have no buffer, so
  399.     you may call this for all requesters to free as much memory as possible.
  400.  
  401.     req - pointer to requester.
  402. *)
  403.  
  404.  
  405. PROCEDURE ChangeReqAttrA(req : ADDRESS; taglist : TagItemPtr) : LONGINT;
  406. INLINE(ReqToolsBase, -48, 9, 8);
  407. (*
  408.     Change requester attributes with supplied taglist.  This is the only
  409.     correct way to change the attributes listed below.
  410.  
  411.     The return code from rtChangeReqAttr() should be ignored unless stated
  412.     otherwise.
  413.  
  414.   INPUTS
  415.     req     - pointer to requester.
  416.     taglist - pointer to array of tags.
  417.  
  418.   TAGS
  419.     for the file requester:
  420.         RTFI_Dir         - STRPTR
  421.                            Name of new directory to position file requester
  422.                            in. The requester's buffer will be deallocated.
  423.         RTFI_MatchPat    - STRPTR
  424.                            New pattern string to match files on.
  425.         RTFI_AddEntry    - (BPTR)
  426.                            THIS *MUST* BE THE LAST TAG (just before TAG_END)!
  427.                            Tagdata must hold a lock on a file or directory
  428.                            you want to add to the file requester's buffer.
  429.                            The lock should have been obtained using Lock(),
  430.                            and you must unlock this lock yourself.
  431.                            It is your responsability to make sure the file
  432.                            or directory is indeed in the directory the file
  433.                            requester is in.
  434.                            If the entry is already in the file requester's
  435.                            buffer it will simply be updated.
  436.                            It is harmless to call this function if the
  437.                            requester's buffer is not initialized.
  438.                            rtChangeReqAttr() will return a boolean to
  439.                            indicate success or failure (out of memory).
  440.         RTFI_RemoveEntry - STRPTR
  441.                            Name of file or directory you want to remove from
  442.                            the file requester's buffer.
  443.                            It is your responsability to make sure the file
  444.                            or directory is indeed in the directory the file
  445.                            requester is in.
  446.                            It is harmless to call this function if the
  447.                            requester's buffer is not initialized.
  448.     for the font requester:
  449.         RTFO_FontName    - STRPTR
  450.                            Set the name of the currently selected font.
  451.         RTFO_FontHeight  - (UWORD)
  452.                            Set the fontsize of the currently selected font.
  453.         RTFO_FontStyle   - (UBYTE)
  454.                            Set the style of the current font.
  455.         RTFO_FontFlags   - (UBYTE)
  456.                            Set the flags of the current font.
  457. *)
  458.  
  459. PROCEDURE ChangeReqAttr(req : ADDRESS) : LONGINT;
  460.  
  461.  
  462. PROCEDURE FileRequestA(filereq : rtFileRequesterPtr;
  463.                        VAR filename : ARRAY OF CHAR;
  464.                        title : STRPTR; taglist : TagItemPtr) : BOOLEAN;
  465. INLINE(ReqToolsBase, -54, 9, 10, 11, 8);
  466. (*
  467.     Get a directory and filename(s), or just a directory from the user.
  468.  
  469.     'filename' should point to an array of at least 108 chars.  The filename
  470.     already in 'filename' will be displayed in the requester when it comes
  471.     up.  When the requester returns 'filename' will probably have changed.
  472.  
  473.   INPUTS
  474.     filereq  - pointer to a struct rtFileRequester allocated with
  475.                rtAllocRequest().
  476.     filename - pointer to an array of chars (must be 108 bytes big).
  477.     title    - pointer to requester window title (null terminated).
  478.     taglist  - pointer to a TagItem array.
  479.  
  480.   TAGS
  481.     RT_Window      - see rtEZRequest()
  482.     RT_ReqPos      - see rtEZRequest()
  483.     RT_LeftOffset  - see rtEZRequest()
  484.     RT_TopOffset   - see rtEZRequest()
  485.     RT_PubScrName  - see rtEZRequest()
  486.     RT_Screen      - see rtEZRequest()
  487.     RT_ReqHandler  - see rtEZRequest()
  488.     RT_WaitPointer - see rtEZRequest()
  489.     RT_DefaultFont - TextFontPtr
  490.                      This tag allows you to specify the font to be used in
  491.                      the requester when the screen font is proportional.
  492.                      Default is GfxBase->DefaultFont.
  493.     RTFI_Flags     - (ULONG)
  494.                      Several flags:
  495.                        FREQF_NOBUFFER    - do _not_ use a buffer to remember
  496.                                            directory contents for the next
  497.                                            time rtFileRequest() is used.
  498.                        FREQF_MULTISELECT - allow multiple files to be
  499.                                            selected. rtFileRequest() will
  500.                                            return a pointer to a rtFileList
  501.                                            structure which will contain all
  502.                                            selected files.
  503.                                            Use rtFreeFileList() to free the
  504.                                            memory used by this file list.
  505.                        FREQF_SELECTDIRS  - set this flag if you wish to
  506.                                            enable the selecting of dirs as
  507.                                            well as files.  You *must* also
  508.                                            set FREQF_MULTISELECT.
  509.                                            Directories will be returned
  510.                                            together with files in rtFileList,
  511.                                            but with StrLen equal to -1.
  512.                                            If you need the length of the
  513.                                            directory's name use strlen().
  514.                        FREQF_SAVE        - Set this if you are using the
  515.                                            requester to save or delete
  516.                                            something.  Double-clicking will
  517.                                            be disabled so it is harder to
  518.                                            make a mistake and select the
  519.                                            wrong file.  If the user enters a
  520.                                            non-existent directory in the
  521.                                            string gadget, a requester will
  522.                                            appear asking if the directory
  523.                                            should be created.
  524.                        FREQF_NOFILES     - Set this if you want to use the
  525.                                            requester to allow the user to
  526.                                            select a directory rather than a
  527.                                            file.  Ideal for getting a
  528.                                            destination directory.
  529.                                            May be used with FREQF_MULTISELECT
  530.                                            and FREQF_SELECTDIRS.
  531.                        FREQF_PATGAD      - When this is set a pattern gadget
  532.                                            will be added to the requester.
  533.                        FREQF_DOWILDFUNC  - Call req->Hook for each entry in
  534.                                            the directory.
  535.                                            Note that there is no tag to set
  536.                                            the hook.  You must initialize
  537.                                            the req->Hook field with a pointer
  538.                                            to a valid hook structure.
  539.                                            See above for more information on
  540.                                            the calling of hooks.
  541.     RTFI_Height    - (ULONG)
  542.                      Suggested height of file requester window.
  543.     RTFI_OkText    - STRPTR
  544.                      Replacement text for "Ok" gadget, max 6 characters long.
  545.  
  546.   RESULT
  547.     ret - TRUE if the user selected a file (check 'filereq->Dir' for the
  548.           directory and 'filename' for the filename) or FALSE if the
  549.           requester was canceled -- or a pointer to a struct rtFileList
  550.           (if FREQF_MULTISELECT was used).
  551.  
  552.   NOTE
  553.     Automatically adjusts the requester to the screen's font.
  554.     If the screen's font is proportional the default font will be used.
  555.  
  556.     If the requester got too big for the screen because of a very large font,
  557.     the topaz.font will be used.
  558.  
  559.     rtFileRequest() checks the pr_WindowPtr of your process to find the
  560.     screen to put the requester on.
  561. *)
  562.  
  563. PROCEDURE FileRequest(filereq : rtFileRequesterPtr;
  564.                       VAR filename : ARRAY OF CHAR;
  565.                       VAR directory : ARRAY OF CHAR;
  566.                       title : ARRAY OF CHAR) : BOOLEAN;
  567.  
  568.  
  569. PROCEDURE FreeFileList(filelist : rtFileListPtr);
  570. INLINE(ReqToolsBase, -60, 8);
  571. (*
  572.     Frees a filelist returned by rtFileRequest() when the FREQF_MULTISELECT
  573.     flag was set.  Call this after you have scanned the filelist and you no
  574.     longer need it.
  575.  
  576.   INPUTS
  577.     filelist - pointer to rtFileList structure, returned by rtFileRequest()
  578.                (may be NULL).
  579. *)
  580.  
  581.  
  582. PROCEDURE EZRequestA(bodyfmt, gadfmt : STRPTR; reqinfo : rtReqInfoPtr;
  583.                      argarray : ADDRESS; taglist : TagItemPtr) : LONGINT;
  584. INLINE(ReqToolsBase, -66, 9, 10, 11, 12, 8);
  585. (*
  586.     This function puts up a requester for you and waits for a response from
  587.     the user. If the response is positive, this procedure returns 1.
  588.     If the response is negative, this procedure returns 0.
  589.     The function may also return an IDCMP flag or a value corresponding with
  590.     one of other possible responses (see below).
  591.  
  592.     'gadfmt' may contain several possible responses.  Seperate these
  593.     responses by a '|'.  For example: "Yes|No", or 'Yes|Maybe|No".  The
  594.     responses should be typed in the same order as they will appear on
  595.     screen, from left to right.  There is no limit to the number of responses
  596.     other than the width of the screen the requester will appear on.
  597.  
  598.     'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a new
  599.     line to be started (surprise, surprise :-).
  600.     You may also include 'printf' style formating codes. The format arguments
  601.     should be pointed to by 'argarray'.
  602.     You can use formatting codes in 'gadfmt' as well.  The arguments for
  603.     this format string should follow the ones for 'bodyfmt'.
  604.  
  605.     NOTE: The formatting is done by exec.library/RawDoFmt(), so be aware that
  606.           to display a 32-bit integer argument you must use "%ld", not "%d",
  607.           since RawDoFmt() is "word-oriented."
  608.  
  609.     The second and third function use a variable number of arguments. These
  610.     functions can be found in 'reqtools[nb].lib'.
  611.     The second function has the RawDoFmt arguments as variable args, the
  612.     third the tags. If you need both this is what you can do:
  613.  
  614.     ...
  615.        {
  616.        ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
  617.  
  618.        rtEZRequest ("String, num: %s, %ld", NULL, "Ok",
  619.                                            TagItemPtrtags, "six", 6);
  620.        }
  621.     ...
  622.  
  623.     You can satisfy the requester with the following keyboard shortcuts:
  624.       'Y' or 'V' for a positive response,
  625.       ESC, 'N', 'R' or 'B' for a negative response.
  626.  
  627.     If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the RETURN key
  628.     is also accepted as a shortcut for the positive response (can be changed
  629.     using RTEZ_DefaultResponse, see below).  The response that will be
  630.     selected when you press RETURN will be printed in bold.
  631.  
  632.     The EZREQF_LAMIGAQUAL flag should be used when you put up a requester
  633.     for a destructive action (e.g. to delete something).  When it is set
  634.     the keyboard shortcuts are limited to Left Amiga 'V' and 'B' so it is
  635.     harder to accidently select something you will regret.
  636.     Note that the RETURN and ESC key remain active!  To disable the RETURN
  637.     key use the EZREQF_NORETURNKEY flag.  The ESC key cannot be disabled.
  638.  
  639.     You may pass a NULL for 'gadfmt', but make sure you know what you are
  640.     doing.  Passing a NULL opens an EZRequester with NO responses, just a
  641.     body text.  This implies the user has no means of "answering" this
  642.     requester.  You must therefore use the RT_IDCMPFlags tag to allow some
  643.     other events to end the requester (e.g. IDCMP_MOUSEBUTTONS,
  644.     IDCMP_INACTIVEWINDOW,...) or you must make use of the ReqHandler feature.
  645.     Using a requester handler you can end the requester by program control.
  646.     This way you can e.g. put up a requester before you start loading a file
  647.     and remove it after the file has been loaded.  Do not pass an empty
  648.     string as 'gadfmt'!
  649.  
  650.     'reqinfo' can be used to customize the requester.  For greater control
  651.     use the tags listed below.  The advantage of the rtReqInfo structure is
  652.     that it is global, where tags have to be specified each function call.
  653.     See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
  654.  
  655.   INPUTS
  656.     bodyfmt  - requester body text, can be format string a la RawDoFmt().
  657.     gadfmt   - text for gadgets (left to right, seperated by '|') or NULL.
  658.     argarray - pointer to array of arguments for format string(s).
  659.     reqinfo  - pointer to a rtReqInfo structure allocated with
  660.                rtAllocRequest() or NULL.
  661.     taglist  - pointer to a TagItem array.
  662.  
  663.   TAGS
  664.     RT_Window       - WindowPtr
  665.                       Window that will be used to find the screen to put the
  666.                       requester on.
  667.                       You *MUST* supply this if you are a task calling this
  668.                       function and not a process! This is because tasks
  669.                       don't have a pr_WindowPtr.
  670.     RT_IDCMPFlags   - (ULONG)
  671.                       Extra idcmp flags to return on.  If one these IDCMP
  672.                       flags causes the requester to abort the return code
  673.                       will equal the flag in question.
  674.     RT_ReqPos       - (ULONG)
  675.                       One of the following:
  676.                         REQPOS_POINTER    - requester appears where the mouse
  677.                                             pointer is (default).
  678.                         REQPOS_CENTERSCR  - requester is centered on the
  679.                                             screen.
  680.                         REQPOS_CENTERWIN  - requester is centered in the
  681.                                             window (only works if the
  682.                                             pr_WindowPtr of your process is
  683.                                             valid or if you use RT_Window).
  684.                                             If RT_Window is NULL the
  685.                                             requester will be centered on
  686.                                             the screen.
  687.                         REQPOS_TOPLEFTSCR - requester appears at the top left
  688.                                             of the screen.
  689.                         REQPOS_TOPLEFTWIN - requester appears at the top left
  690.                                             of the window (only works if the
  691.                                             pr_WindowPtr of your process is
  692.                                             valid or if you use RT_Window).
  693.                       The requester will always remain in the visible part of
  694.                       the screen, so if you use the Workbench 2.0 ScreenMode
  695.                       preferences editor to enlarge your Workbench screen and
  696.                       you scroll around, the requester will always appear in
  697.                       the part you can see.
  698.                       REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to
  699.                       the visible part of the screen. So if you use one of
  700.                       these the requester will be appear in the center or the
  701.                       top left off what you can see of the screen as opposed
  702.                       to the entire screen.
  703.                       REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
  704.                       REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively
  705.                       when there is no parent window.  So you can safely use
  706.                       these without worrying about the existence of a window.
  707.     RT_LeftOffset   - (ULONG)
  708.                       Offset of left edge of requester relative to position
  709.                       specified with RT_ReqPos (does not offset the requester
  710.                       when RT_ReqPos is REQPOS_POINTER).
  711.     RT_TopOffset    - (ULONG)
  712.                       Offset of top edge of requester relative to position
  713.                       specified with RT_ReqPos (does not offset the requester
  714.                       when RT_ReqPos is REQPOS_POINTER).
  715.     RT_PubScrName   - STRPTR
  716.                       Name of public screen requester should appear on. When
  717.                       this tag is used the RT_Window tag will be ignored.
  718.                       If the public screen is not found the requester will
  719.                       open on the default public screen.
  720.                       Only works on Kickstart 2.0!  reqtools.library does
  721.                       not check this, it is up to you *NOT* to use this tag
  722.                       on Kickstart 1.3 or below!
  723.                       Note that the 1.3 version of reqtools.library also
  724.                       understands and supports this tag (on 2.0).
  725.     RT_Screen       - ScreenPtr
  726.                       Address of screen to put requester on.  You should
  727.                       never use this, use RT_Window or RT_PubScrName.
  728.     RT_ReqHandler   - rtHandlerInfoPtr
  729.                       Using this tag you can start an "asynchronous"
  730.                       requester. ti_TagData of the tag must hold the address
  731.                       of a pointer variable to a rtHandlerInfo structure.
  732.                       The requester will initialize this pointer and will
  733.                       return immediately after its normal initialization.
  734.                       The return code will not be what you would normally
  735.                       expect.  If the return code is _not_ equal to
  736.                       CALL_HANDLER an error occured and you should take
  737.                       appropriate steps. If the return code was CALL_HANDLER
  738.                       everything went ok and the requester will still be up!
  739.                       See the explanation for rtReqHandler() below for the
  740.                       following steps you have to take.
  741.     RT_WaitPointer  - (BOOL)
  742.                       If this is TRUE the window calling the requester will
  743.                       get a standard wait pointer set while the requester is
  744.                       up.  This will happen if you used the RT_Window tag or
  745.                       if your process's pr_WindowPtr is valid.  Note that
  746.                       after the requester has finished your window will be
  747.                       ClearPointer()-ed.  If you used a custom pointer in
  748.                       your window you will have to re-set it, or not use the
  749.                       RT_WaitPointer tag and put up a wait pointer yourself.
  750.                       Defaults to FALSE.  It is advised you use this tag as
  751.                       much as possible.
  752.     RTEZ_ReqTitle   - STRPTR
  753.                       Title of requester window, default is "Request" unless
  754.                       the requester has less than 2 responses, then the
  755.                       default title is "Information".
  756.     RTEZ_Flags      - (ULONG)
  757.                       Flags for rtEZRequest():
  758.                         EZREQF_NORETURNKEY - turn off the RETURN key as
  759.                                              shorcut for positive response.
  760.                         EZREQF_LAMIGAQUAL  - keyboard shortcuts are limited
  761.                                              to Left Amiga 'V' and 'B', ESC
  762.                                              and RETURN.
  763.                         EZREQF_CENTERTEXT  - centers each line of body text
  764.                                              in the requester window. Useful
  765.                                              for about requesters.
  766.     RTEZ_DefaultResponse - (ULONG)
  767.                       Response value that will be returned when the user
  768.                       presses the return key.  Will be ignored if the
  769.                       EZREQF_NORETURNKEY flag is set.  The text for this
  770.                       response will be printed in bold. Default is 1.
  771.  
  772.   RESULT
  773.     ret - 1 (TRUE) for leftmost (positive) response, then each consecutive
  774.           response will return 1 more, the rightmost (false) respons will
  775.           return 0 (FALSE), so 1,2,3,...,num-1,0 -- or idcmp flag.
  776.  
  777.   NOTE
  778.     Automatically adjusts the requester to the screen's font.
  779.  
  780.     rtEZRequest() checks the pr_WindowPtr of your process to find the
  781.     screen to put the requester on.
  782. *)
  783.  
  784. PROCEDURE EZRequest(bodyfmt : ARRAY OF CHAR;
  785.                     gadfmt : ARRAY OF CHAR; reqinfo : rtReqInfoPtr;
  786.                     argarray : ADDRESS) : LONGINT;
  787.  
  788. PROCEDURE EZRequestTags(bodyfmt : ARRAY OF CHAR;
  789.                         gadfmt : ARRAY OF CHAR; reqinfo : rtReqInfoPtr;
  790.                         argarray : ADDRESS; taglist : TagItemPtr) : LONGINT;
  791.  
  792. (* no return value versions of above routines *)
  793. PROCEDURE vEZRequestA(bodyfmt : ARRAY OF CHAR;
  794.                       gadfmt : ARRAY OF CHAR; reqinfo : rtReqInfoPtr;
  795.                       taglist : TagItemPtr; argarray : ADDRESS);
  796.  
  797. PROCEDURE vEZRequest(bodyfmt : ARRAY OF CHAR;
  798.                      gadfmt : ARRAY OF CHAR; reqinfo : rtReqInfoPtr;
  799.                      argarray : ADDRESS);
  800.  
  801.  
  802. PROCEDURE GetStringA(VAR buffer : ARRAY OF CHAR; maxchars : LONGINT;
  803.                      title : STRPTR; reqinfo : rtReqInfoPtr;
  804.                      taglist : TagItemPtr) : BOOLEAN;
  805. INLINE(ReqToolsBase, -72, 9, 0, 10, 11, 8);
  806. (*
  807.     Puts up a string requester to get a line of text from the user.
  808.     The string present in 'buffer' upon entry will be displayed, ready to
  809.     be edited.
  810.  
  811.     'reqinfo' can be used to customize the requester.  For greater control
  812.     use the tags listed below.  The advantage of the rtReqInfo structure is
  813.     that it is global, where tags have to be specified each function call.
  814.     See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
  815.  
  816.   INPUTS
  817.     buffer   - pointer to buffer to hold characters entered.
  818.     maxchars - maximum number of characters that fit in buffer (EX-cluding
  819.                the 0 to terminate the string !).
  820.     title    - pointer to null terminated title of requester window.
  821.     reqinfo  - pointer to a rtReqInfo structure allocated with
  822.                rtAllocRequest() or NULL.
  823.     taglist  - pointer to a TagItem array.
  824.  
  825.   TAGS
  826.     RT_Window        - see rtEZRequest()
  827.     RT_IDCMPFlags    - see rtEZRequest()
  828.     RT_ReqPos        - see rtEZRequest()
  829.     RT_LeftOffset    - see rtEZRequest()
  830.     RT_TopOffset     - see rtEZRequest()
  831.     RT_PubScrName    - see rtEZRequest()
  832.     RT_Screen        - see rtEZRequest()
  833.     RT_ReqHandler    - see rtEZRequest()
  834.     RT_WaitPointer   - see rtEZRequest()
  835.     RTGS_Width       - (ULONG)
  836.                        Width of requester window in pixels.  This is only a
  837.                        suggestion. rtGetString() will not go below a certain
  838.                        width.
  839.     RTGS_AllowEmpty  - (BOOL)
  840.                        If RTGS_AllowEmpty is TRUE an empty string will also
  841.                        be accepted and returned.  Defaults to FALSE, meaning
  842.                        that if the user enters an empty string the requester
  843.                        will be canceled.
  844.  
  845.   RESULT
  846.     ret - TRUE if user entered something, FALSE if not. If one of your idcmp
  847.           flags caused the requester to end 'ret' will hold this flag.
  848.  
  849.   NOTE
  850.     The contents of the buffer will NOT change if the requester is aborted.
  851.  
  852.     Automatically adjusts the requester to the screen's font.
  853.  
  854.     rtGetString() checks the pr_WindowPtr of your process to find the
  855.     screen to put the requester on.
  856. *)
  857.  
  858. PROCEDURE GetString(VAR buffer : ARRAY OF CHAR; maxchars : LONGINT;
  859.                     title : ARRAY OF CHAR; reqinfo : rtReqInfoPtr) : BOOLEAN;
  860.  
  861.  
  862. PROCEDURE GetLongA(VAR longvar : LONGINT; title : STRPTR;
  863.                    reqino : rtReqInfoPtr; taglist : TagItemPtr) : BOOLEAN;
  864. INLINE(ReqToolsBase, -78, 9, 10, 11, 8);
  865. (*
  866.     Puts up a requester to get a signed long (32-bit) number from the user.
  867.  
  868.     'reqinfo' can be used to customize the requester.  For greater control
  869.     use the tags listed below.  The advantage of the rtReqInfo structure is
  870.     that it is global, where tags have to be specified each function call.
  871.     See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
  872.  
  873.   INPUTS
  874.     &longvar - address of long (32 bit!) variable to hold result.
  875.     title    - pointer to null terminated title of requester window.
  876.     reqinfo  - pointer to a rtReqInfo structure allocated with
  877.                rtAllocRequest() or NULL.
  878.     taglist  - pointer to a TagItem array.
  879.  
  880.   TAGS
  881.     RT_Window        - see rtEZRequest()
  882.     RT_IDCMPFlags    - see rtEZRequest()
  883.     RT_ReqPos        - see rtEZRequest()
  884.     RT_LeftOffset    - see rtEZRequest()
  885.     RT_TopOffset     - see rtEZRequest()
  886.     RT_PubScrName    - see rtEZRequest()
  887.     RT_Screen        - see rtEZRequest()
  888.     RT_ReqHandler    - see rtEZRequest()
  889.     RT_WaitPointer   - see rtEZRequest()
  890.     RTGL_Min         - (ULONG)
  891.                        Minimum allowed value. If the user tries to enter a
  892.                        smaller value the requester will refuse to accept it.
  893.     RTGL_Max         - (ULONG)
  894.                        Maximum allowed value, higher values are refused.
  895.     RTGL_Width       - (ULONG)
  896.                        Width if requester window in pixels.  This is only a
  897.                        suggestion. rtGetLong() will not go below a
  898.                        certain width.
  899.     RTGL_ShowDefault - (BOOL)
  900.                        If this is TRUE (default) the value already in
  901.                        'longvar' will be displayed in the requester when it
  902.                        comes up. If set to FALSE the requester will be empty.
  903.  
  904.   RESULT
  905.     ret - TRUE if user entered a number, FALSE if not. If one of your idcmp
  906.           flags caused the requester to end 'ret' will hold this flag.
  907.  
  908.   NOTE
  909.     'longvar' will NOT change if the requester is aborted.
  910.  
  911.     Automatically adjusts the requester to the screen's font.
  912.  
  913.     rtGetLong() checks the pr_WindowPtr of your process to find the
  914.     screen to put the requester on.
  915. *)
  916.  
  917. PROCEDURE GetLong(VAR longvar : LONGINT; title : ARRAY OF CHAR;
  918.                   reqino : rtReqInfoPtr) : BOOLEAN;
  919.  
  920.  
  921. PROCEDURE FontRequestA(fontreq : rtFontRequesterPtr; title : STRPTR;
  922.                        taglist : TagItemPtr) : BOOLEAN;
  923. INLINE(ReqToolsBase, -96, 9, 11, 8);
  924. (*
  925.     Let the user select a font and a style (optional).
  926.  
  927.     Setting certain flags may result in the calling of a caller-supplied
  928.     hook. See rtFileRequest() for more information on the calling of this
  929.     hook.
  930.  
  931.     Hook types ('param[0]') currently implemented for rtFontRequest():
  932.  
  933.         REQHOOK_WILDFONT:
  934.             Set the FREQF_DOWILDFUNC flag to activate. The requester will
  935.             call your hook for each font in the system's font list.
  936.             'param[1]' will hold the address of a struct TextAttr. If your
  937.             hook returns TRUE the font will be skipped.
  938.  
  939.     Finally note that when you change your hook or your hook's behaviour
  940.     you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())!
  941.  
  942.   INPUTS
  943.     fontreq  - pointer to a struct rtFontRequester allocated with
  944.                rtAllocRequest().
  945.     title    - pointer to requester window title (null terminated).
  946.     taglist  - pointer to a TagItem array.
  947.  
  948.   TAGS
  949.     RT_Window         - see rtEZRequest()
  950.     RT_ReqPos         - see rtEZRequest()
  951.     RT_LeftOffset     - see rtEZRequest()
  952.     RT_TopOffset      - see rtEZRequest()
  953.     RT_PubScrName     - see rtEZRequest()
  954.     RT_Screen         - see rtEZRequest()
  955.     RT_ReqHandler     - see rtEZRequest()
  956.     RT_WaitPointer    - see rtEZRequest()
  957.     RT_DefaultFont    - TextFontPtr
  958.                         This tag allows you to specify the font to be used in
  959.                         the requester when the screen font is proportional.
  960.                         Default is GfxBase->DefaultFont.
  961.     RTFO_Flags        - (ULONG)
  962.                         Several flags:
  963.                           FREQF_NOBUFFER      - do not buffer the font list
  964.                                                 for subsequent calls to
  965.                                                 rtFontRequest().
  966.                           FREQF_FIXEDWIDTH    - only display fixed-width fonts.
  967.                           FREQF_COLORFONTS    - display color fonts also.
  968.                           FREQF_CHANGEPALETTE - change the screen's palette
  969.                                                 to match that of a selected
  970.                                                 color font.
  971.                           FREQF_LEAVEPALETTE  - leave the palette as it is
  972.                                                 when exiting rtFontRequest()
  973.                                                 Useful in combination with
  974.                                                 FREQF_CHANGEPALETTE.
  975.                           FREQF_SCALE         - allow fonts to be scaled
  976.                                                 when they don't exist in the
  977.                                                 requested size.
  978.                                                 (works on Kickstart 2.0 only,
  979.                                                  has no effect on 1.2/1.3).
  980.                           FREQF_STYLE         - include gadgets so the user
  981.                                                 may select the font's style.
  982.                           FREQF_DOWILDFUNC    - Call req->Hook for each font.
  983.                                                 Note that there is no tag to
  984.                                                 set the hook.  You must
  985.                                                 initialize the req->Hook
  986.                                                 field with a pointer to a
  987.                                                 valid hook structure.
  988.                                                 See rtFileRequest() for more
  989.                                                 information on the calling of
  990.                                                 this hook.
  991.     RTFO_Height       - (ULONG)
  992.                         Suggested height of font requester window.
  993.     RTFO_OkText       - STRPTR
  994.                         Replacement text for "Ok" gadget.  Maximum 6 chars.
  995.                         (7 is still ok, but not esthetically pleasing)
  996.     RTFO_SampleHeight - (ULONG)
  997.                         Height of font sample display in pixels (default 24).
  998.     RTFO_MinHeight    - (ULONG)
  999.                         Minimum font size displayed.
  1000.     RTFO_MaxHeight    - (ULONG)
  1001.                         Maximum font size displayed.
  1002.  
  1003.   RESULT
  1004.     bool - TRUE if the user selected a font (freq->Attr holds the font),
  1005.            FALSE if the requester was canceled.
  1006. *)
  1007.  
  1008. PROCEDURE FontRequest(fontreq : rtFontRequesterPtr;
  1009.                       title : ARRAY OF CHAR) : BOOLEAN;
  1010.  
  1011.  
  1012. PROCEDURE PaletteRequestA(title : STRPTR; reqinfo : rtReqInfoPtr;
  1013.                            taglist : TagItemPtr) : LONGINT;
  1014. INLINE(ReqToolsBase, -102, 10, 11, 8);
  1015. (*
  1016.     Put up a palette requester so the user can change the screen's colors.
  1017.  
  1018.     The colors are changed in the viewport of the screen the requester will
  1019.     appear on, so that is where you will find them after the palette
  1020.     requester returns.
  1021.  
  1022.     The selected color is returned, so you can also use this requester to let
  1023.     the user select a color.
  1024.  
  1025.     'reqinfo' can be used to customize the requester.  For greater control
  1026.     use the tags listed below.  The advantage of the rtReqInfo structure is
  1027.     that it is global, where tags have to be specified each function call.
  1028.     See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
  1029.  
  1030.   INPUTS
  1031.     title   - pointer to requester window title (null terminated).
  1032.     reqinfo - pointer to a rtReqInfo structure allocated with
  1033.               rtAllocRequest() or NULL.
  1034.     taglist - pointer to a TagItem array.
  1035.  
  1036.   TAGS
  1037.     RT_Window        - see rtEZRequest()
  1038.     RT_ReqPos        - see rtEZRequest()
  1039.     RT_LeftOffset    - see rtEZRequest()
  1040.     RT_TopOffset     - see rtEZRequest()
  1041.     RT_PubScrName    - see rtEZRequest()
  1042.     RT_Screen        - see rtEZRequest()
  1043.     RT_ReqHandler    - see rtEZRequest()
  1044.     RT_WaitPointer   - see rtEZRequest()
  1045.     RT_DefaultFont   - TextFontPtr
  1046.                        This tag allows you to specify the font to be used in
  1047.                        the requester when the screen font is proportional.
  1048.                        Default is GfxBase->DefaultFont.
  1049.     RTPA_Color       - (ULONG)
  1050.                        Initially selected color of palette.  Default is 1.
  1051.  
  1052.   RESULT
  1053.     color - the color number of the selected color or -1 if the user
  1054.             canceled the requester.
  1055.  
  1056.   NOTE
  1057.     Automatically adjusts the requester to the screen's font.
  1058.     If the screen's font is proportional the default font will be used.
  1059.  
  1060.     If the requester got too big for the screen because of a very large font,
  1061.     the topaz.font will be used.
  1062.  
  1063.     rtPaletteRequest() checks the pr_WindowPtr of your process to find the
  1064.     screen to put the requester on.
  1065. *)
  1066.  
  1067. PROCEDURE PaletteRequest(title : ARRAY OF CHAR; reqinfo : rtReqInfoPtr) : LONGINT;
  1068.  
  1069.  
  1070. PROCEDURE ReqHandlerA(handlerinfo : rtHandlerInfoPtr; sigs : SignalSet;
  1071.                       taglist : TagItemPtr) : LONGINT;
  1072. INLINE(ReqToolsBase, -108, 9, 0, 8);
  1073. (*
  1074.     This function should be called if you used the RT_ReqHandler tag with a
  1075.     requester function.
  1076.  
  1077.     The requester you used the tag with will have returned immediately after
  1078.     its initialization and will have initialized a pointer to a rtHandlerInfo
  1079.     structure for you.
  1080.     You should now do the following:
  1081.  
  1082.     Check the DoNotWait field. If it is FALSE you have to wait for the
  1083.     signals in the WaitMask field (plus your own signals if you like).
  1084.     If any of the signals in WaitMask are received or DoNotWait was not FALSE
  1085.     you have to call rtReqHandler() and check its return value for one of
  1086.     the following values:
  1087.  
  1088.       CALL_HANDLER    - Check DoNotWait again, Wait() if you have to
  1089.                         and call rtReqHandler() again. In other words, loop.
  1090.       everything else - normal return value, requester has finished. This
  1091.                         return value will be the same as if the requester
  1092.                         had run normally.
  1093.  
  1094.     You must pass the signals you received to rtReqHandler().
  1095.  
  1096.     NOTE: if you want to wait for your own signals do not do so if
  1097.           DoNotWait is TRUE.  Call rtReqHandler() and if you must know
  1098.           if one of your signals arrived use SetSignal() to find this out.
  1099.           If you are waiting for a message to arrive at a message port you
  1100.           can simple call GetMsg and check if it is non-null.
  1101.           DoNotWait will naturally only be TRUE when it absolutely,
  1102.           positively has to be.  A multitasking machine as the Amiga should
  1103.           use Wait() as much as possible.
  1104.  
  1105.     This is an example of a "requester loop":
  1106.  
  1107.     ...
  1108.     struct rtHandlerInfo *hinfo;
  1109.     ULONG ret, mymask, sigs;
  1110.  
  1111.     ...
  1112.        /* calculate our mask */
  1113.        mymask = 1 << win->UserPort->mp_SigBit;
  1114.  
  1115.        /* We use the RT_ReqHandler tag to cause the requester to return
  1116.           after initializing.
  1117.           Check the return value to see if this setup went ok. */
  1118.        if (rtFontRequest (req, "Font", RT_ReqHandler, &hinfo, TAG_END)
  1119.                                                            == CALL_HANDLER) {
  1120.           do {
  1121.             /* Wait() if we can */
  1122.             if (!hinfo->DoNotWait)
  1123.                sigs = Wait (hinfo->WaitMask | mymask);
  1124.  
  1125.             /* check our own message port */
  1126.             while (msg = GetMsg (win->UserPort)) {
  1127.                ...
  1128.                /* here we handle messages received at our windows IDCMP               ...
  1129.                   port */
  1130.                ...
  1131.                }
  1132.  
  1133.             /* let the requester do its thing (remember to pass 'sigs') */
  1134.             ret = rtReqHandler (hinfo, sigs, TAG_END);
  1135.  
  1136.             /* continue this loop as long as the requester is up */
  1137.             } while (ret == CALL_HANDLER)
  1138.  
  1139.           /* when we get here we know the requester has finished, 'ret'
  1140.              is the return code. */
  1141.           ...
  1142.           }
  1143.        else notify ("Error opening requester!");
  1144.     ...
  1145.  
  1146.   INPUTS
  1147.     handlerinfo - pointer to handler info structure initialized by using
  1148.                   the RT_ReqHandler tag when calling a requester function.
  1149.     sigs        - the signals received by previous wait, will be ignored if
  1150.                   hinfo->DoNotWait was TRUE.
  1151.     taglist     - pointer to a TagItem array.
  1152.  
  1153.   TAGS
  1154.     RTRH_EndRequest - supplying this tag will end the requester. The return
  1155.                       code from rtReqHandler() will _not_ be CALL_HANDLER,
  1156.                       but the requester return code.  If the tagdata of this
  1157.                       tag is REQ_CANCEL the requester will be canceled, if it
  1158.                       is REQ_OK the requester will be ok-ed.
  1159.                       In case of an EZRequest tagdata should be the return
  1160.                       code of the requester (TRUE, FALSE or 2,3,4,...).
  1161.  
  1162.   RESULT
  1163.     ret - CALL_HANDLER if you have to call rtReqHandler() again,
  1164.           or the normal return value from the requester.
  1165. *)
  1166.  
  1167. PROCEDURE ReqHandler(handlerinfo : rtHandlerInfoPtr; sigs : SignalSet) : LONGINT;
  1168.  
  1169.  
  1170. PROCEDURE SetWaitPointer(window : WindowPtr);
  1171. INLINE(ReqToolsBase, -114, 8);
  1172. (*
  1173.     Change the window's pointer image to that of a wait pointer.  Call this
  1174.     function whenever your program will be busy doing something for a lengthy
  1175.     period of time.
  1176.  
  1177.     It is recomended you call this function before calling any of the
  1178.     requester functions.  This way if the user clicks in your window he will
  1179.     know he must respond to the requester before doing anything else.  See
  1180.     also the RT_WaitPointer tag for an automatic way of setting the wait
  1181.     pointer.
  1182.  
  1183.   INPUTS
  1184.     window - pointer to the window to receive the wait pointer.
  1185. *)
  1186.  
  1187.  
  1188. (*
  1189.  * the following functions are for the advanced reqtools user
  1190.  * who whishes to write his/her own (complementary) requesters
  1191.  *)
  1192. PROCEDURE GetVScreenSize(screen : ScreenPtr; VAR width, height : LONGINT);
  1193. INLINE(ReqToolsBase, -120, 8, 9, 10);
  1194. (*
  1195.     Use this function to get the size of the visible portion of a screen.
  1196.  
  1197.     The value returned by rtGetVScreenSize() can be used for vertical
  1198.     spacing.  It will be larger for interlaced and productivity screens.
  1199.     Using this number for spacing will assure your requester will look
  1200.     good on an interlaced and a non-interlaced screen.
  1201.  
  1202.     Current return codes are 2 for non-interlaced and 4 for interlaced.
  1203.     These values may change in the future, don't depend on them too much.
  1204.     They will in any case remain of the same magnitude.
  1205.  
  1206.   INPUTS
  1207.     screen    - pointer to the screen.
  1208.     widthptr  - address of an ULONG variable to hold the width.
  1209.     heightptr - address of an ULONG variable to hold the height.
  1210. *)
  1211.  
  1212.  
  1213. PROCEDURE SetReqPosition(reqpos : LONGINT; newwindow : NewWindowPtr;
  1214.                          screen : ScreenPtr; window : WindowPtr);
  1215. INLINE(ReqToolsBase, -126, 0, 8, 9, 10);
  1216. (*
  1217.     Sets newwindow->LeftEdge and newwindow->TopEdge according to reqpos.
  1218.  
  1219.     Except for the left- and topedge 'newwindow' must already be completely
  1220.     initialized.
  1221.  
  1222.     The newwindow->LeftEdge and newwindow->TopEdge already in the NewWindow
  1223.     structure will be used as offsets to the requested position.  If you'd
  1224.     like a window at position (25,18) from the top left of the screen you
  1225.     would fill newwindow->LeftEdge with 25, newwindow->TopEdge with 18 and
  1226.     call rtSetReqPosition() with reqpos equal to REQPOS_TOPLEFTSCR.
  1227.  
  1228.     Don't forget to make sure newwindow->LeftEdge and newwindow->TopEdge
  1229.     are 0 if you don't want to offset your window.
  1230.  
  1231.     In case of REQPOS_POINTER you can use them to point to your window's
  1232.     hotspot, where the pointer should point.  If you call rtSetReqPosition()
  1233.     with the left- and topedge equal to 0 you'd get a window appearing with
  1234.     its top- and leftedge equal to the current pointer position.
  1235.  
  1236.     Note that the screen pointer may _NOT_ be NULL.  If you have your own
  1237.     window open you can supply yourwindow->WScreen to this function.
  1238.  
  1239.     The window pointer is only required if reqpos is REQPOS_CENTERWIN or
  1240.     REQPOS_TOPLEFTWIN.  Even in this case you may call rtSetReqPosition()
  1241.     with a NULL window pointer.  The positions will simply fall back to
  1242.     REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR respectively.
  1243.  
  1244.   INPUTS
  1245.     reqpos    - one of the REQPOS_... constants usable with RT_ReqPos.
  1246.     newwindow - pointer to your (already initialized) NewWindow structure.
  1247.     screen    - pointer to screen the requester will appear on.
  1248.     window    - pointer to parent window or NULL.
  1249. *)
  1250.  
  1251.  
  1252. PROCEDURE Spread(VAR posarray  : ARRAY OF LONGINT;
  1253.                  VAR sizearray : ARRAY OF LONGINT;
  1254.                  totalsize, min, max, num : LONGINT);
  1255. INLINE(ReqToolsBase, -132, 8, 9, 0, 1, 2, 3);
  1256. (*
  1257.     Evenly spread a number of objects over a certain length.
  1258.     Primary use is for arrangement of gadgets in a window.
  1259.  
  1260.     Example:
  1261.  
  1262.     'sizearray' holds following values: 4, 6, 4, 2 and 8,
  1263.     'totalsize' is 24 (= 4 + 6 + 4 + 2 + 8),
  1264.     'min' is 3, 'max' is 43,
  1265.     and finally, 'num' is 5.
  1266.  
  1267.     After calling rtSpread() 'posarray' would hold the following
  1268.     values: 3, 11, 19, 26 and 31.
  1269.  
  1270.     My attempt at a visual representation:
  1271.  
  1272.         |                                            |
  1273.         |  |                                      |  |
  1274.         |  OOOO    OOOOOO    OOOO    OO    OOOOOOOO  |
  1275.         |  |                                      |  |
  1276.         |         1    1    2    2    3    3    4    4
  1277.         0----5----0----5----0----5----0----5----0----5
  1278.  
  1279.   INPUTS
  1280.     posarray  - pointer to array to be filled with positions.
  1281.     sizearray - pointer to array of sizes.
  1282.     totalsize - total size of all objects (sum of all values in sizearray).
  1283.     min       - first position to use.
  1284.     max       - last position, first _NOT_ to use.
  1285.     num       - number of objects (size of posarray and sizearray).
  1286. *)
  1287.  
  1288.  
  1289. PROCEDURE ScreenToFrontSafely(screen : ScreenPtr);
  1290. INLINE(ReqToolsBase, -138, 8);
  1291. (*
  1292.     Brings the specified screen to the front of the display, but only after
  1293.     checking it is still in the list of currently open screens.
  1294.  
  1295.     This function can be used to bring a screen back to the front of the
  1296.     display after bringing another screen to the front.  If the first screen
  1297.     closed while you where busy it is harmless to call this function, unlike
  1298.     calling the normal ScreenToFront().
  1299.  
  1300.   INPUTS
  1301.     screen - pointer to the screen.
  1302. *)
  1303.  
  1304.  
  1305. END ReqTools.